1. Locate the XPDintegStart.bat under Windows and XPDintegStart.sh under Linux in the <XPDINTEG_HOME> directory (see chapter ‎2.5 Expeditor integrator file and directory structure) and execute it. Make sure the user account under which the XPDintegStart.bat/sh is executed has sufficient access rights to the given local file system folders. dd
2. If the Expeditor integrator was installed as a service:
   1. Windows: Start the Windows Service from the Windows Management Console
   2. Linux: Run the Linux service from a root console
   3. Restart the Expeditor integrator runtime server (not recommended)

Note: If problems with the messaging back-end connection are experienced, the connection and queues can be re-set by running the resetscript/XPDintegReset.bat/sh. This deletes all messages from the local queues, the current internal OSGi Config Store, all log and trace files (including the transaction log). Please, use this command with care!
Important: If start-up problems are encountered a StartUpProblems.log file is created under <XPDINTEG_HOME>/workspace/logs.

Stop Expeditor integrator runtime

• through the Expeditor integrator console: Locate the console window (under Windows named <XPDINTEG_HOME>/.../java.exe) that was started by the XPDintegStart.bat/sh in the <XPDINTEG_HOME> directory (see chapter ‎2.5 Expeditor integrator file and directory structure), enter close (or exit) and press Enter:
• by toggling the service: If the Expeditor integrator was installed as a …
  1. Windows Service, locate the service in the Windows Service panel and stop or re-start IBM Lotus Expeditor integrator from there.
  2. Linux Service, open a root console and run the command: service XPDintegSvc start|stop|restart
• through the PlatformRestart control message: Control Message with MessagePurpose=PlatformRestart can be sent to the CtrlQ. If this operation is enabled and allowed (credentials), the Expeditor integrator runtime can be re-started or stopped (refer to chapter ‎5.11.1 Securing Operations for securing flows).
  Note: Stopping the runtime shuts the Administrator out from accessing the Expeditor integrator platform. After stopping the runtime, Expeditor integrator can only be started manually (or through the Windows Service if installed).

The IBM Lotus Expeditor integrator Windows Service can also be managed from a console window like the Linux service (option 2). Under Linux, copy the XPDintegSvc file to the /etc/init.d directory. For Windows, locate the <XPDINTEG_HOME>/service/XPDintegSvc(.exe) file which understands commands and optional parameters:

• Commands to start, restart and stop Expeditor integrator service (without console window):
  • Windows:
    XPDintegSvc.exe start
    XPDintegSvc.exe restart
    XPDintegSvc.exe stop
  • Linux:
    service XPDintegSvc start
    service XPDintegSvc restart
    service XPDintegSvc stop
• Optional parameter to start Expeditor integrator service in a console window and with running reset before start-up:
  Windows: XPDintegSvc.exe start –reset –console
  Linux: service XPDintegSvc start –reset -console
  • with console, but without running reset before start-up:
    XPDintegSvc.exe start –console
    Note: Console logging needs to be switched on if log messages should be displayed (see chapter ‎5.7 Log Messages).
  • Re-start Expeditor integrator service in a console window with/without running reset before start-up:
    XPDintegSvc.exe restart –reset –console
    XPDintegSvc.exe restart –console

Note: If a manual service start is invoked using the XPDintegSvc.exe program under Windows, the provided start-up parameters -reset and/or -console are persisted. This means that during subsequent re-starts of Expeditor integrator service (e.g. from the Windows Services panel), the previous parameter settings are re-used. If these parameters settings are to be changed, the XPDintegSc.exe must be run again with the desired parameters. This also applies for ACS Flows which use the XPDintegSvc.exe to re-start the Expeditor integrator platform. The previoius parameter settings are re-used unless new ones are provided.

Expeditor integrator logging to the OSGi Console

1. permanently (also available after re-start):
   by editing the following line in <XPDINTEG_HOME>/rcp/eclipse/features/com.ibm.rcp.integrator.feature_<version>.<build>/handler.properties
   
   -Dcom.ibm.rcp.integrator.showflowstatus=true
2. temporarily (not set anymore after platform reset):
   by editing the following line in <XPDINTEG_HOME>/workspace/.config/rcpinstall.properties
   
   -Dcom.ibm.rcp.integrator.showflowstatus=true

Note: Changes to handler.properties and rcpinstall.properties require a platform re-start. Changes to the handler.properties file require resetting and re-starting the Expeditor integrator platform (stop Expeditor integrator and run resetscript/XPDintegReset.bat before starting it again). Caution: All messages in local queues will be delete during Reset!

The installation and un-installation of Expeditor integrator is further explained in chapter ‎2.3 Installation of Expeditor integrator and ‎2.4 Uninstalling of Expeditor integrator.

Expeditor integrator file based logging

a) permanently (also available after re-start):

a) temporarily (not set anymore after platform reset):

Note: Changes to handler.properties and rcpinstall.properties require a platform re-start. Changes to the handler.properties file require resetting and re-starting the Expeditor integrator platform (stop Expeditor integrator and run resetscript/XPDintegReset.bat before starting it again). Caution: All messages in local queues will be delete during Reset!

The flow status log files can be found in folder /workspace/logs. The current log file is XPDinteg_FlowStatus-0.log. The log file is rotating when exceeding a size of 4 MB per default. The default rotation log file count is 10. This means that the oldest file is overwritten when there are 10 log files located in the log directory. Both of these values can be configured by adding the following two lines to the handler.properties or the rcpinstall.properties file:

-Dcom.ibm.rcp.integrator.logflowstatusfilesize=<MAX_LOG_FILE_SIZE_IN_BYTE>

-Dcom.ibm.rcp.integrator.logflowstatusmaxfilenumber=<MAX_LOG_FILE_COUNT>

Expeditor integrator platform Reset

The IBM micro broker (Expeditor integrator messaging service) and the transaction service store their data under the persistent folder.

In case of configuration errors or configuration changes (of messaging service/micro broker) and problems with micro broker, the Expeditor integrator platform can be reset by executing this script:

The platform reset script whipes all content of the following directories:

When Expeditor integrator is started up again, the content of the XPDinteg.xml configuration file is re-applied.

Note: If problems with the messaging back-end connection are experienced, the connection and queues can be re-set by performing this platform Reset. This deletes all messages from the local queues, the current internal OSGi Config Store, all log and trace files (including the transaction log). Please, use this command with care!

Remote Platform Restart

1. IBM Lotus Expeditor Server (Expeditor Client Manager)
2. IBM WebSphere Premises Server

The IBM Lotus Expeditor Server also allows for remote management of the Eclipse RCP features and plug-ins. Please, note that the current Expeditor integrator use case configuration is based on OSGi Configuration Admin rather then Eclipse Preferences Service. Direct configuration through the Preferences Service is not possible. But, the Expeditor Server can be used to manage Expeditor integrator’s configuration through updating the XPDinteg.xml configuration file (see below).

The IBM WebSphere Premises Server was initially developed for remote management of the RFID Reader concentrators at the remote location (Edge Devices or Data Capture devices). Since the Data Capture devices were built on the same technology stack as Expeditor integrator and also use the OSGi Configuration Admin as configuration store, the Premises Server can also manage Expeditor integrator’s configuration. For this, Premises Server licenses and two further Data Capture bundles are required (Please, contact your IBM Representative for further information about the WebSphere Premises option.).

However, for small environments where a Device Management Server is not available, the additionally developed Custom Config Service allows for using a local configuration file to update the Expeditor integrator configuration (config/XPDinteg.xml). Details about available configuration parameters and their possible values are given in the configuration section (see Default Queue names section ‎3).

Note: It is important to understand that the configuration through the XPDinteg.xml file and the Custom Config Service approach is for environments without a Device Management Server (DMS) only. A mix of both approaches is NOT recommended since configuration changes applied by the DMS are not reflected in the XPDinteg.xml file and will be overwritten as soon as the XPDinteg.xml file is changed.

The XPDinteg.xml file can be changed through any of the following methods:

• Option_1: locally in the Expeditor integrator installation folder (on the remote server),
• Option_2: remotely through Expeditor integrator ConfigUpdate message
• Option_3: through updating the XPDinteg.xml via file transfer (e.g. by using the Expeditor Server or software distribution tools).

Option 1 Manually updating the XPDinteg xml file on the remote server

• The changed XPDinteg.xml file is simply copied into the <XPDINTEG_HOME>/config/new subfolder. This subfolder is monitored by a specific Resource Adapter that is configured by default:
  
  Listing 40: LocalFileSystem Resource Adapter configuration for manual configuration update

<adapter type="XPDINTEG_FILE_SYSTEM_ADAPTER" name="UC210AdapterForConfigUpdate1">

     <!-- sync mode -->

     <polling>

          <interval>60000</interval>

          <meta-data>ASCII-config/new/XPDinteg.xml</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/ConfigUpdate/LocalFileSystem/ConfigurationUpdateFile/LocalFileSystemAdapter</topic>

     </polling>

     <configuration>

          <param name="ResourceType" value="LocalFileSystemMonitorForConfigUpdate"/>

          <param name="TransferConfirmationMode" value="DELETE"/>

          <param name="DestinationName" value="config/new/XPDinteg.xml"/>

     </configuration>

</adapter>

• As soon as the new XPDinteg.xml file is recognized by this adapter, the
  com/ibm/integrator/flowtriggerevent/ConfigUpdate/LocalFileSystem/ConfigurationUpdateFile/LocalFileSystemAdapter event is fired that triggers the manual update default flow:
  
  Default_ConfigUpdateManual.flow
• This flow overwrites the existing config/XPDinteg.xml file with the new one in config/new directory. It also creates the updated system configuration file under config/system.
• The new XPDinteg.xml XML structure is validated by the LocalConfigUpdate_TransformAndValidate Activity.
• Finally, the LocalConfigUpdate_ConfigStoreUpdate Activity applies the configuration changes to the OSGi Configuration Admin store.

Note: Since the ConfigUpdateManual.flow runs in transactional context, the configuration update will be rolled back in case of errors.

Option 2 Replacing the XPDinteg xml file with a new file provided through an update message

1. a new (updated) XPDinteg.xml file or
2. a specific Expeditor integrator XML structure which contains the configured parameters as parameter-value-pairs of the XPDintegConfig.xml file (see XPDINTEG_CONFIG_XML structure in Listing 41).

The JMS Custom Header property ResourceCmd is used to differentiate between option a) and b).

For updating the whole XPDinteg.xml (a):

And for the list of configuration parameters which need to be updated (b):

Listing 41: The XPDINTEG_CONFIG_XML structure is used for updating single Expeditor integrator properties through the ConfigUpdate message.

<?xml version="1.0" encoding="utf-8"?>

     <configurations>

          <configuration pid="com.ibm.rcp.integrator.customeventservice">

               <properties>

                    <property name="MaintenanceMode" value="ON"/>

               </properties>

          </configuration>

     </configurations>

...

• The DestinationPath and -Name parameters contain the target path in the local file system where the configuration file in the payload is detached to and applied to the OSGi Configuration Admin store.
• MessageId, TransactionId, LocationId, MessageSrcId and HeaderVersion must be provided so that the log message can be created appropriately.

The JMS Adapter (Resource Adapter) recognizes a new message in the CtrlQ and fires the corresponding event with this topic:
com/ibm/integrator/flowtriggerevent/ConfigUpdate/LocalFileSystem/ConfigurationUpdateFile/JmsAdapter

This event is received by the ACS which kicks off the configured default configuration update flow which provides transactional security for the configuration update as well:

Flow file name: Default_ConfigUpdate.flow

The triggered default flow will contain

• ConfigUpdate_TransformAndValidate Activity which validates the XML schema of the config file
• ConfigUpdate_FileWriteToFileSystem Activities for writing the new XPDinteg.xml and XPDintegConfig.xml
• ConfigUpdate_ConfigStoreUpdate Activity which finally updates the OSGi Config Admin store.
• PlatformRestart_PlatformRestart which re-starts the Expeditor integrator platform if it was indicated in the ResourceCmd header of the ConfigUpdate message.

Notes:

• There is no corresponding reply message. Log and Business Event (transaction status information) messages are available for appropriate status information.
• The ConfigUpdate Flow can be further secured by checking the provided credentials in the JMS Custom header property Credentials of the ConfigUpdate control message (see chapter 5.11.1 Securing Operations).

Please, refer to the Using the IBM Expeditor integrator platform for further details of how ConfigUpdate messages can be created and sent (see Ref_2).

Option 3 Replacing the XPDinteg xml file with a new file provided through remote file transfer facility

• connect directly to the MQ
• connect to the Microbroker running inside the DTS component of the Premises server

The Premises web interface is used to create and send new configurations to the Expeditor integrator. This creates a message that is put to the EDGE.OUT.Q (QM: IBM.RFID.QM). This message is forwared automatically by the DTS component to the corresponding Expeditor integrator instance according the EdgeId. (Scenario 2). If the DTS component is disabled (it’s a simple Windows service), the message then stays on the EDGE.OUT.Q and can be picked up from there by the Expeditor integrator. (Scenario 1)


Figure 12: Reload Config Scenario with the Premises Server

The WebSphere Premises server update scenario contains the following steps:

1. The Administrator changes in parameters the configuration for a certain remote Expeditor integrator instance using the Premises Server user interface
2. The Administrator triggers a configuration reload for this Expeditor integrator instance
3. The Premises Server sends a notification message to the Expeditor integrator
4. The Expeditor integrator receives the notification and triggers the Data Capture bundles
5. The EdgeConfigAgent wrapper component is reacting on the message and triggers the EdgeConfigAgent by using its public API
6. The Data Capture bundle retrieves the new configuration from the Premises server over HTTP

Configuration data for the EdgeConfigAgent

<custom-config-service>

     …

     <deployment-mode value="PREMISES">

          <premises-deployment>

               <param name="com.ibm.rfid.edge.config.autostart" value="true"/>

               <param name="com.ibm.rfid.edge.config.bootstrap" value="true"/>

               <param name="com.ibm.rfid.edge.config.bootstrap.overrides" value="false"/>

               <param name="com.ibm.rfid.edge.config.interval" value="10000"/>

               <url>

                    <property>com.ibm.rfid.edge.config.url</property>

                    <value>http://nickel.isicc.de.ibm.com:9080/ibmrfidadmin/premises.sl?action=getconfig&amp;edge=&lt;edge_id&gt;&amp;version=6.1</value>

               </url>

          </premises-deployment>

     </deployment-mode>

     ...

</custom-config-service>

• Settings for the new connection factory
• Settings for the Remote Queue on the Premises Server
• Settings for the SyncQ and DeadletterQ on the Premises Server
• Settings for the local Premises Config Queue
• Settings for the bridge

Table 37: Settings for the connection factory

<administered-objects>

…

<!-- connection factory for the MQ running on the Premises Server -->

<connection-factory name="ConnectionFactory2" type="MQ" jndiKey="jms/XPDinteg-PremisesConnectionFactory">

     <params>

          <param name="hostname" value="nickel.isicc.de.ibm.com"/>

          <param name="port" value="1415"/>

          <param name="channel" value="SYSTEM.DEF.SVRCONN"/>

          <param name="queue-manager" value="IBM.RFID.QM"/>

          <param name="clientid"value C00100"/>

     </params>

</connection-factory>

<administered-objects>

….

<!-- Queue definitions for the Premises Server -->

<queue purpose="PremisesServerSyncQ" type="MQ" jndiKey="jms/ XPDinteg_PremisesSyncQueue">

     <params>

          <param name="queue-name" value="SYSTEM.CHANNEL.SYNCQ"/>

     </params>

</queue>

<queue purpose="PremisesServerDeadletterQ" type="MQ" jndiKey="jms/ XPDinteg_PremisesDeadletterQueue">

     <params>

          <param name="queue-name" value="SYSTEM.DEAD.LETTER.QUEUE"/>

     </params>

</queue>

<queue purpose="PremisesConfigQ" type="MQ" jndiKey="jms/ XPDinteg_PremisesConfigQ">

     <params>

          <param name="queue-name" value="EDGE.OUT.Q"/>

     </params>

</queue>

<!-- END Queue definitions for the Premises Server -->

….

</administered-objects>

<queues>

…

<!-- definition for the local PremisesConfigQ -->

     <queue purpose="LocalPremisesConfigQueue">

          <queue-name>XPDinteg_LocalPremisesConfigQueue</queue-name>

          <jndi-key>jms/XPDinteg_LocalPremisesConfigQueue</jndi-key>

     </queue>

…

</queues>

<pipes>

….

<!-- Pipe definition for the Premises connection -->

<pipe name="Premises Pipe">

     <jndi-connection connection-factory-key="jms/XPDinteg-PremisesConnectionFactory" sync-queue-key="jms/XPDinteg_PremisesSyncQueue" dead-letter-queue-key="jms/XPDinteg_PremisesDeadletterQueue"/>

          <flow name="PremisesConfigFlow" direction="INBOUND">

          <!-- The source and target types map onto the destination definitions in the bridge. -->

               <source name="mqQ" type="JNDI">

                    <value>jms/MQ_PremisesConfigQ</value>

               </source>

               <target name="ubQ" type="QUEUE" value="XPDinteg_LocalPremisesConfigQueue">

               </target>

               <jms-selector>C00100</jms-selector>

          </flow> 

</pipe>

…

</pipes>

• Settings for the new connection factory
• Settings for the topic received from the Microbroker
• Settings for the local Premises Config Queue
• Settings for the bridge

Table 41: Settings for the connection factory

<administered-objects>

…

<!-- connection factory for the MQ running on the Premises Server -->

<connection-factory name="ConnectionFactory2" type="MQTTJMS" jndiKey="jms/XPDinteg-PremisesConnectionFactory">

     <params>

          <param name="hostname" value="nickel.isicc.de.ibm.com"/>

          <param name="port" value="1883"/>

     </params>

</connection-factory>

…

</administered-objects>

<administered-objects>

….

<topic purpose="PremisesReloadTopic" type="MQTTJMS" jndiKey="jms/ premisesDTSTopic">

     <params>

          <param name="topic-name" value="reload/C999"/>

     </params>

</topic>

….

</administered-objects>

<queues>

… 

<!-- queues needed for the bridge in case of connecting to the DTS of the Premises Server-->

     <queue purpose="LocalPremisesSyncQueue">

          <queue-name>XPDinteg_PremisesSyncQueue</queue-name>

          <jndi-key>jms/XPDinteg_PremisesSyncQueue</jndi-key>

     </queue>

     <queue purpose="LocalPremisesDeadletterQueue">

          <queue-name>XPDinteg_PremisesDeadletterQueue</queue-name>

          <jndi-key>jms/XPDinteg_PremisesDeadletterQueue</jndi-key>

     </queue>

     <!-- definition for the local PremisesConfigQ -->

     <queue purpose="LocalPremisesConfigQueue">

          <queue-name>XPDinteg_LocalPremisesConfigQueue</queue-name>

          <jndi-key>jms/XPDinteg_LocalPremisesConfigQueue</jndi-key>

     </queue>

…

</queues>

<pipes>

….

<!-- Pipe definition for the Premises connection -->

<pipe name="Premises Pipe">

     <jndi-connection connection-factory-key="jms/XPDinteg-PremisesConnectionFactory" sync-queue-key="jms/XPDinteg_PremisesSyncQueue" dead-letter-queue-key="jms/XPDinteg_PremisesDeadletterQueue"/>

     <flow name="PremisesConfigFlow" direction="INBOUND">

     <!-- The source and target types map onto the destination definitions in the bridge. -->

     <source name="ubTopic" type="JNDI">

          <value>jms/premisesDTSTopic</value>

     </source>

     <target name="ubQ" type="QUEUE" value="XPDinteg_PremisesConfigQueue"></target>

     </flow>

</pipe>

…

</pipes>

• Complete reinstall
  This method is equal to the initial installation procedure that is described earlier in this document (see chapter ‎2.3 Installation of Expeditor Integrator). All files in the old installation location (<XPDINTEG_HOME> directory) are removed and replaced with a new Expeditor integrator package (all application files and configuration). This also involves the deletion of the local queues that might contain messages which belong to a transaction.
  Please, use this method with great care and when no transactions are pending.

• Eclipse plug-in (component) update
  This is the state-of-the-art method to update Eclipse RCP based applications. The Eclipse Rich Client Platform services ensure that only plug-ins (components/services) with resolved dependencies are finally started. They also allow application components updates without requiring a re-start, re-configuration of the platform / application nor the deletion of local queues (apart from the case when micro broker related services and components are effected; please refer to the configuration section ‎3 in this document for details).
  
  Example: The file footer Activity BuildPriceUpdateFileFooterActivity in a FileTransfer ACS flow needs to be modified because the file footer creation algorithm was changed. This can be dynamically done by remotely updating the com.ibm.rcp.integrator.acsactivities application component (bundle) with a new version.

• Installation of new components to extend the application (bundles)
  This is an extension to the second option. The Expeditor integrator can be simply extended with new ACS flows by providing new flow definition files through the FileTransfer methods (see ‎chapter 4.6.1 Inbound Resource Mapper) and adding new ACS Activities by installing the components (plug-ins) that implement them using the remote Eclipse plug-in or OSGi bundle installation. This gives the Expeditor integrator powerful extension options and allows for remote adjustment of flows and use case implementations.

Expeditor integrator custom deployment options

…

<common>

     <id>&lt;BootStrapId&gt;</id>

     <boot-strap value="ON">

          <bootstrap-id-type>MACAddress</bootstrap-id-type>

     </boot-strap>

</common>…

The bootstrap-id-type IdFile is describing an arbitrary file containing a unique ID which is already available on the remote server (where the Expeditor integrator runtime is deployed). For example, this ID file was created placed by other system management software (e.g. Tivoli). If UniqueIdFile is used as Boot Strap ID, an additional parameter is required – the path to the ID file (see Listing 44).

Listing 44: Custom Deployment configuration example: Boot Strap ID

 …

<common>

     <id>&lt;BootStrapId&gt;</id>

     <boot-strap value="ON">

          <bootstrap-id-type>UniqueIdFile</bootstrap-id-type>

          <params>

               <param name=”idFileLocation” value=”C:\myUnique.id”/>

          <params>

     </boot-strap>

</common> 

• Transaction Service
• Messaging Service
• Application Control Service (ACS)
• Resource Mapper
• Custom Config Service
• (Configuration details for these services can be found in section ‎3.)

The <messaging-service> section in the XPDinteg.xml contains only the configuration data for the Connection Factory to the business backbone. This includes the definition for the 2 required configuration queues (for retrieving the customized configuration files), the SyncQ and DeadletterQ required by MQ. In addition, it contains a JMS Selector ID to explicitly filter for the Boot Strap ID of the local Expeditor integrator runtime so that the unique configuration for this runtime is selected and received from the configuration queue at business backbone.

Listing 45: JMS Selector configuration

 …

<flow name="inQFlow" direction="INBOUND">

     <source name="mqQ" type="JNDI">

          <value>jms/MQ_ConfigQOut</value>

     </source>

     <target name="ubQ" type="QUEUE" value="XPDinteg_ConfigQIn"></target>

     <jms-selector>BootStrapId = '&lt;BootStrapId&gt;'</jms-selector>

</flow>

 …

<custom-config-service>

     <deployment-mode value="CUSTOM">

          <custom-deployment>

               <jndiConnectionFactoryKey>jms/XPDinteg_ConnectionFactory</jndiConnectionFactoryKey>

               <targetQJNDI>jms/XPDinteg_ConfigQOut</targetQJNDI>

          </custom-deployment>

     </deployment-mode>

</custom-config-service>

…

<!--

********************************************************************

* ACS - Application CONTROL SERVICE 

* Flow and Activity configuration 

******************************************************************** -->

<application-control-service>

     <definition-settings>

          <directory>flowdefs</directory>

          <poll-interval>120000</poll-interval>

          <extension>flow</extension>

          <retryInterval>30000</retryInterval>

     </definition-settings>

     <permissions>

          <multiple-flows-per-topic>false</multiple-flows-per-topic>

     </permissions>

     <activity-configurations>

          <configuration activity="XPDINTEG_VALIDATE_TRANSFORM_ACTIVITY">

               <param name="XSDLocation" value="config\system\XPDinteg.xsd"/>

               <param name="XSLTLocation" value="config\system\XPDinteg.xsl"/>

               <param name="OutputXMLLocation" value="config\system\XPDintegConfig.xml"/>

          </configuration>

          <configuration activity="XPDINTEG_PLATFORM_RESTART">

               <param name="EnableScriptExecution" value="TRUE"/>

          </configuration>

     </activity-configurations>

</application-control-service>

• <boot-strap> section is removed from the <common> section
• The new configuration file which is sent needs to contain
  

  <messaging-service>

  <microbroker>

  <core>

  <clean-start>true</clean-start>

  
  
  for the Messaging Service. This is required because the micro broker needs to be reset after changed queue definitions.

Example for a rollout scenario for a production environment

1. Create a reference image
   • Install the product on a reference machine (<XPDintegHome> = /opt/ibm/lotus/integrator)
   • Configure the reference installation with a startup configuration containing
     • All required flows in the <XPDintegHome>/flowdefs
     • A XPDinteg.xml
       • without a connection to a messaging backend
       • only one resource adapater monitoring for the basic configuration file (default ConfigurationUpdate resource monitor)
     • A basic configuration file in <XPDintegHome>/config/basic/XPDinteg_WILDCARD.xml
       • It contains a placeholder like “LOCATIONWILDCARD” for location specific configuration parts
       • It contains a connection to the messaging backend, but only global queues, no location specific queues
       • Listens on a “ConfigQIn” via a MessageSelector for its specific configuration (e.g. JMS_Property LocationId = ’Filialnummer’)
       • No resource adapters for data collection and data distribution are configured
     • adopted daemon script “xpdinteg”
   • Create an archive of the reference image (tar cpvf - lotus | gzip > XPDintegImage.tar.gz)
2. Distribute the reference image via the customers software distribution mechanism
   • Reference image is copied to the target machine
   • Reference image is extracted in the directory /opt/ibm
   • Service daemon script “xpdinteg” is deployed to /etc/init.d
3. Custom deployment scripts start
   • These are custom scripts that must be created and may depend on the customers software distribution mechanism
   • Custom scripts update the placeholder in the basic configugration file <XPDintegHome>/config/basic/XPDinteg_ WILDCARD.xml "LOCATIONWILDCARD" will be replaced with a location property that is determined by the script, e.g. the hostname or a StoreID that is written in an ID file, that already exists in the customers environment for identification purposes of machines that are installed in the remote locations.
   • Custom scripts copy the updated basic configuration to <XPDintegHome>/config/new/XPDinteg.xml to be picked up by the ConfigurationUpdateFlow
   • Custom scripts create a file <XPDintegHome>/BootStrapInfo.txt. All information required by the backend systems is added to this file, e.g. Hostname, Operating system, LocationID, CountryCode etc.)
4. First start-up of Lotus Expditor integrator using the daemon
   • The default configuration update flow detects the XPDinteg.xml in <XPDintegHome>/config/new/XPDinteg.xml and deploys the new configuration
   • A restart incl. a reset is triggered
5. Second start-up
   • The product is configured with the basic configuration now
   • A Resource monitor picks up the <XPDintegHome>/BootStrapInfo.txt file and sends it to the messaging backend via a dedicated queue
   • Backend system receives the message containing the file and is having now all required information to:
     • Create location specific queues on the messaging backend systems
     • Create a custom XPDinteg.xml for this location with all required adapters, resource monitors, queues, backend connections etc.
   • Messaging backend sends the custom XPDinteg.xml to the queue ConfigQOut on messaging backend
   • New Configuration file is received by the product on the queue ConfigQIn and applies the new location specific configuration
   • A restart including a reset is triggered
6. Third start-up
   • The product is now fully operational

Figure 14: Example for a Deployment scenario in a production environment

Custom Deployment Tool

1. Unzip the CustomDeploymentTool.zip file under the
   <XPDINTEG_HOME>/tools/CustomDeploymentTool
   1. Edit the mq.properties file and provide the following information
      • QM=<QueueManager>
      • QM_HOST=<Hostname-where-the-Queuemanager-is-running>
      • QM_PORT=<Portnumber>
      • QM_SERVER_CONNECTION=<ChannelName>
      • receivingQ=<Name-of-the-ConfigInQ> Default: ConfigQIn
      • sendingQ=<Name-of-the-ConfigOutQ> Default: ConfigQOut
      • deadLetterQ=<Name-of-the-DeadletterQ>
   2. Edit the bootstrap.properties and provide the mapping between the Boot Strap ID and the location of the unique configuration file (XPDinteg.xml) for the Expeditor integrator runtime with this specific Boot Strap ID:
      • If Boot Strap ID is the MACAddress:
        00-0C-29-F9-92-FD=XPDintegXML/XPDinteg-100.xml
      • If Boot Strap ID is the IPAdress:
        10.0.1.12=XPDintegXML/XPDinteg-101.xml
      • If Boot Strap ID is the HostName:
        server1.abc.de=XPDintegXML/XPDinteg-102.xml
      • If Boot Strap ID is the UniqueFileId:
        <yourUniqueId>=XPDintegXML/XPDinteg-103.xml
   3. Provide all required configuration files (all files mentioned in the bootstrap.properties file), The default directory for these files is: <XDPINTEG_HOME>/tools/customdeploymenttool/XPDintegXML
2. Open a console window and change to the directory of the custom deployment tool (<XPDINTEG_HOME>/tools/CustomDeploymentTool).
3. Start the tool by running the CustomDeployment.bat
4. To close the tool, please press Enter.

Note: Please, make sure that the CustomDeployment.bat points to an existing JDK (by default it points to the JDK provided with the Expeditor integrator).

Expeditor integrator Maintenance Mode

Entering the Local Maintenance Mode can be triggered by a Local Filesystem File or a Control Message with the MessagePurpose “StartLocalMaintenance”.

Please refer to chapter Local Maintenance Flow for more details.

Log Messages

• OSGi / Eclipse standard logging (see chapter ‎5.7.1 Level of Log Messages)
• Custom Log Service (see chapter ‎5.7.1 Level of Log Messages)
• Tivoli Monitoring (see chapter ‎5.7.2 micro broker and micro broker bridge Logging)

Local log files are also created and could be retrieved by FileRequest messages (see Table 50 in chapter ‎9.4.1 Where to look first in case of Problems (Log Files) with available log files).

Level of Log Messages

• XPDINTEG_BUNDLEEVENT
• XPDINTEG_LOGEVENT

The TEC log and trace files are stored in

• <XPDINTEG_HOME>/persistent/tec/eif.log and
• <XPDINTEG_HOME>/persistent/tec/eif.trc

The TEC libraries do not provide options to limit the trace and log file size. The Expeditor integrator v1.0 passes the log file names as parameters on to the used TEC libraries. Currently, there is no way to limit the size of these two files (even from XPDinteg).

It is recommended to turn the logging and tracing only on in defined environments by setting TecLogLevel=ALL and TecTraceLevel=ALL (in XPDinteg.xml) and OFF again under production conditions

Please, refer to chapter ‎4.7 Application Control Service configuration for configuration details.

Performance Parameter

• not exceed 512 MB dynamic memory (RAM) during runtime
• not consist of more then 2000 files and must not be larger then 300 MB on disk (footprint)
• be able to process 80000 price update messages within 2 hours (special case of BUC100: initial price upload)

Please, check chapter ‎5.11 Expeditor Integrator Tuning for tuning recommendations.

Crash of Expeditor integrator

• Delete the <XPDINTEG_HOME>\persistent and the <XPDINTEG_HOME>\workspace folder
• Run the XPDintegReset.bat in <XPDINTEG_HOME>\resetscript
• Start the Expeditor integrator by either executing the XPDintegStart.bat or restarting the corresponding Windows Service

Important: If the \persistent folder is deleted, all messages that are currently sitting in local queues are deleted as well. Please, be very cautious with this operation!

If the problem still exists, please consider contacting IBM Support. Please, run the IBM Support Assistant and provide the created support information (see chapter ‎6.8 IBM Support Assistant).
Please, refer to chapter 5.1 Start / Stop Expeditor integrator for the start up procedure.

Backup and Restore

• config
• flowdefs
• workspace\log

In case of system and hard disk crash on the remote server, the Expeditor integrator could be re-installed and the backed up folders could be restored to their original location.

Note about the message persistence: Since the \persistent folder contains the local Expeditor integrator queues, the queues in the backup folder will contain all those messages that were in the queues during the creation of the backup. If a potential crash happens a longer time after the back-up, all messages (saved during the back-up process) will have been processed already. If the backed up messages are restored in the \persistent folder, these messages will be re-processed. This will cause wrong business behavior of the application (e.g. old price updates will be applied after a restore). Therefore, it is highly recommended to delete the /persistent folder after a restore operation and before the application restart.

It is also recommended to delete the /workspace content and re-run the XPDintegReset.bat (see chapter ‎5.9 Crash of Expeditor integrator).

Please, refer to chapter 2.5 Expeditor integrator file and directory structure for the current footprint of the Expeditor integrator.

Expeditor integrator Tuning

• ACS Activities which use script execution can be globally enabled/disabled (see chapter ‎5.11.1.1 Allow Script Execution)
• Each ACS Flow can be secured through credentials which must be provided in the JMS Custom Header property Credentials (see chapter ‎5.11.1.2 Securing ACS Flows)

Allowing Script Execution

• XPDINTEG_FILE_EXECUTE
• XPDINTEG_EXECUTE_LOCAL_SCRIPT
• XPDINTEG_PLATFORM_RESTART

Listing 48: Example for enabling / disabling script execution globally

<application-control-service>

     <activity-configurations>

          <configuration activity="XPDINTEG_FILE_EXECUTE">

               <param name="EnableScriptExecution" value="TRUE"/>

          </configuration>

          <configuration activity="XPDINTEG_EXECUTE_LOCAL_SCRIPT">

               <param name="EnableScriptExecution" value="TRUE"/>

          </configuration> <configuration activity="XPDINTEG_PLATFORM_RESTART">

               <param name="EnableScriptExecution" value="TRUE"/>

          </configuration>

...

…

     <XPDintegActivity

          Name="PlatformRestart_PlatformRestart"

          ActivityName="XPDINTEG_PLATFORM_RESTART"

          LocalScriptFile="services/XPDintegRestart.bat"

          EnableScriptExecution="TRUE"

          Command="restart"

          Param="console"

     />

…

<osgi> 2008/01/08 15:25:45.875 SEVERE FMBB3030 bridge JMS connection [Ljava.lang.String;@7ebc7ebc

encountered a JMS exception, the connection will be closed andvattempts made to restart it, reason:

javax.jms.JMSException:

MQJMS2002: failed to get message from MQ queue ::class.method=unknown ::thread=

Thread-3 ::loggername=com.ibm.micro.utils

2008.01.08 15:25:47 MQJMS1023E rollback failed

2008/01/08 15:25:47.500 SEVERE FMBB3030 bridge JMS connection [Ljava.lang.String;@7ebc7ebc encountered a

JMS exception, the connection will be closed and attempts made to restart it, reason: javax.jms.JMSException:

MQJMS2002: failed to get message from MQ queue ::class.method=unknown ::thread=Thread-3 ::loggername=

com.ibm.micro.utils 2008.01.08 15:25:50 MQJMS1023E

rollback failed

Lotus Expeditor integrator provides an OSGi console command checkmsgserverstatus for displaying the status of connection to the back-end server. If Expeditor integrator loses the connectivity to the back-end server due to physical network problems, it may take a long time (approximately 6-8 minutes or more) to realize the disconnection. Within this time, the OSGi console command checkmsgserverstatus will show integrator as still being connected to the back-end server. When the physical network connection is available again, integrator is able to realize the restoration of connection to back-end server within one retry interval (default is 60 seconds).

The issue may be seen due to the insufficient default Heartbeat Interval (HBINT) parameter setting on the channel of the MQ back-end server. The HBINT is the time out interval after which an exception listener is invoked in the JMS classes for MQ when connectivity problems between client and server occur for the used server connection channel. The default value of the HBINT is 300 seconds (5 minutes).

The WebSphere MQ classes for JMS rely on the underlying Java Runtime Environment to throw a SocketException if a TCP/IP connection to the queue manager is broken. The WebSphere MQ classes for JMS will use the value of the HBINT property to set the time-out on the socket object that represents the TCP/IP connection. This means that, if an application connects to a queue manager using the CLIENT transport, the higher the value of HBINT, the longer it will take for the exception listener to be invoked for informing the application that the TCP/IP connection is broken.

If there is a requirement to detect connection failures sooner, the value of the HBINT property should be lowered. Note that if the HBINT property is set too low, there will be an increase in network traffic. CPU usage will also increase, as there would be more heart beat flows to be processed. If the TCP keepalive parameter is used in the network, please make sure that it is set to a value higher than that of HBINT.

The following steps are required for setting the HBINT:

FTP Connections:
Unreliable connections from the FTP Resource Adapter to target FTP servers can also cause time out problems. The optional FTP connection parameter DataTimeOut was introduced to avoid the FTP connection thread to hang if no clean disconnecting from the FTP server was possible, e.g. during unexpected shutdown (see chapter ‎4.4.2 FTP Resource Adapter). Furthermore, it is recommended for unreliable FTP network environments to lower the connection time out parameter on the FTP server accordingly.

Running the Expeditor integrator with limited or increased memory

and run

This command returns the used Java version, if the requested memory heap size (of 2048 MB) can be allocated. Otherwise, an error will be displayed stating that the instantiation of the heap memory failed.

(See memory limitations in chapter Memory usage and queue size)

Reduce Application Load due to Polling

These properties can be overridden in the rcpinstall.properties present in the
<XPDINTEG_HOME>/rcp/eclipse/plugins/com.ibm.rcp.base_<version> plug-in.

In cases where customers have restriction on the size of this file, these two properties can be modified in the rcpinstall.properties file.

Start Expeditor integrator in Linux console 'Screen mode'

• Open a (remote) console window, e.g. with


• ssh 192.168.40.120 –l my_ssh_user
• In this session, start a second console with the Screen command by entering:


• screen
• Switch to root user into the created background console and start Expeditor integrator in there (OSGi console and logging data is visible):


• sudo su
  cd /opt/ibm/lotus/Integrator
  ./XPDintegStart.sh
• Detach this console (and move it to background) by entering these keyboard keys:


• 'Ctrl – a' and then press 'd'
• Exit your (remote) console.
• Now, any other remote SSH login can re-attach to the created Linux console in which the OSGi console of Expeditor integrator running.
• Enter the following command to re-attach to the previously created console with Expeditor integrator:


• screen –x
• If more than one screen session is displayed, the one with the OSGi console needs to be selected with:


• screen –x pidof_screen_session

Remote access to OSGi Console when running as Service

Follow these steps to enable telnet access to the OSGi console: